SH

NAME

SYNOPSIS

DESCRIPTION

Definitions

Commands

A pipeline is a sequence of one or more commands separated by | (or, for historical compatibility, by ^). The standard output of each command but the last is connected by a pipe(2) to the standard input of the next command. Each command is run as a separate process; the shell waits for the last command to terminate. The exit status of a pipeline is the exit status of the last command.

A list is a sequence of one or more pipelines separated by ;, &&, or ||, and optionally terminated by ;. Of these three symbols, ; has a lower precedence than that of && and ||. The symbols && and || also have equal precedence. A semicolon (;) causes sequential execution of the preceding pipeline. The symbol && (||) causes the list following it to be executed only if the preceding pipeline returns a zero (non-zero) exit status. An arbitrary number of new-lines may appear in a list, instead of semicolons, to delimit commands.

A command is either a simple-command or one of the following. Unless otherwise stated, the value returned by a command is that of the last simple-command executed in the command.

for name [ in word ... ] do list done

Each time a for command is executed, name is set to the next word taken from the in word list. If in word ... is omitted, then the for command executes the do list once for each positional parameter that is set (see Parameter Substitution below). Execution ends when there are no more words in the list.

case word in [ pattern [ |

pattern ] ... ) list ;; ] ... esac A case command executes the list associated with the first pattern that matches word. The form of the patterns is the same as that used for file-name generation (see File Name Generation) except that a slash, a leading dot, or a dot immediately following a slash need not be matched explicitly, and the match is case sensitive.

if list then list [ elif list then list ] ... [ else list ] fi

The list following if is executed and, if it returns a zero exit status, the list following the first then is executed. Otherwise, the list following elif is executed and, if its value is zero, the list following the next then is executed. Failing that, the else list is executed. If no else list or then list is executed, then the if command returns a zero exit status.

while list do list done

A while command repeatedly executes the while list and, if the exit status of the last command in the list is zero, executes the do list; otherwise the loop terminates. If no commands in the do list are executed, then the while command returns a zero exit status; until may be used in place of while to negate the loop termination test.

(list)

Execute list in a sub-shell. The shell creates a new environment in which to execute the list, but does not fork a sub-shell as a Unix system would. The original environment is restored on completion.

{list;}

list is simply executed.

name () {list;}

Define a function which is referenced by name. The body of the function is the list of commands between { and }. Execution of functions is described below (see Execution).

The following words are only recognized as the first word of a command and when not quoted:

if then else elif fi case esac for while until do done { }  

Comments

Command Substitution

Parameter Substitution

name = value [ name = value ] ...

Pattern-matching is not performed on value. There cannot be a function and a variable with the same name.

${parameter}

The value, if any, of the parameter is substituted. The braces are required only when parameter is followed by a letter, digit, or underscore that is not to be interpreted as part of its name. If parameter is * or @, all the positional parameters, starting with $1, are substituted (separated by spaces). Parameter $0 is set from argument zero when the shell is invoked.

${parameter:-word}

If parameter is set and is non-null, substitute its value; otherwise substitute word.

${parameter:=word}

If parameter is not set or is null set it to word; the value of the parameter is substituted. Positional parameters may not be assigned to in this way.

${parameter:?word}

If parameter is set and is non-null, substitute its value; otherwise, print word and exit from the shell. If word is omitted, the message ``parameter null or not set´´ is printed.

${parameter:+word}

If parameter is set and is non-null, substitute word; otherwise substitute nothing.

In the above, word is not evaluated unless it is to be used as the substituted string, so that, in the following example, pwd is executed only if d is not set or is null:

echo ${d:-`pwd`}

If the colon (:) is omitted from the above expressions, the shell only checks whether parameter is set or not (It is not clear what this means).

The following parameters are automatically set by the shell:

#

The number of positional parameters in decimal.

-

Flags supplied to the shell on invocation or by the set command.

?

The decimal value returned by the last synchronously executed command.

$

The process number of this shell.

!

The process number of the last background command invoked.

~

The shell reserves all variables beginning with a ~ for its own internal use and these variables cannot be accessed by the user.

The following parameters are used by the shell:

CDPATH The search path for the cd command. (Note that becuase a colon is used by MSDOS to indicate a drive, a semi-colon is used to separate the path names instead of a colon - this implies that the CDPATH variable must be set using single or double quotes to surround the value).

EXTENDED_LINE This parameter defines a file containing a list of command which can accept an Extended Command Line using the indirect command file character @. When a command which can process the Extended Command Line finds a parameter starting with a @ in the command list, treats the rest of the parameter as a file and reads the parameters from that file. Examples of this functionality include the Standard Linker and Librarian. The filename defined by EXTENDED_LINE contains a list of command (including the .exe or .com extension) separated by a newlines. If the command is in upper case, the file name on the command line is set up with backslashes as the directory separator. Otherwise, slashes (Unix style) are used. This functionality allows the user to get round the 127 byte command line length limit of MSDOS.

HISTFILE The file where command history is saved across login sessions. The default value is $HOME/history.sh.

HOME The default argument (home directory) for the cd command.

IFS Internal field separators, normally space, tab, and new-line.

MAIL If this parameter is set to the name of a mail file and the MAILPATH parameter is not set, the shell informs the user of the arrival of mail in the specified file.

MAILCHECK This parameter specifies how often (in seconds) the shell will check for the arrival of mail in the files specified by the MAILPATH or MAIL parameters. If set to 0, the shell will check before each prompt.

MAILPATH A colon (:) separated list of file names. If this parameter is set, the shell informs the user of the arrival of mail in any of the specified files. Each file name can be followed by % and a message that will be printed when the modification time changes. The default message is "you have mail".

PATH The search path for commands (see Execution below). The user may not change PATH if executing under rsh. (Note that because a colon is used by MSDOS to indicate a drive, a semi-colon is used to separate the path names instead of a colon - this implies that the PATH variable must be set using single or double quotes to surround the value).

PS1 Primary prompt string, by default ``$ ´´.

PS2 Secondary prompt string, by default ``> ´´.

SHELL When the shell is invoked, it scans the environment (see Environment below) for this name. If it is found and there is an 'r' in the file name part of its value, the shell becomes a restricted shell.

TMP The location of temporary files created by the shell.

The shell gives default values to PATH, PS1, PS2, SHELL, HOME and IFS.  

Blank Interpretation

File Name Generation

*

Matches any string, including the null string.

?

Matches any single character.

[ ... ]

Matches any one of the enclosed characters. A pair of characters separated by - matches any character lexically between the pair, inclusive. If the first character following the opening ``[´´ is a ``!´´ any character not enclosed is matched.

Quoting

; & ( ) | ^ < > new-line space tab

A character may be quoted (i.e., made to stand for itself) by preceding it with a \. The pair \new-line is ignored. All characters enclosed between a pair of single quote marks (´´), except a single quote, are quoted. Inside double quote marks (""), parameter and command substitution occurs and \ quotes the characters \, `, ", and $. "$*" is equivalent to "$1 $2 ...", whereas "$@" is equivalent to "$1" "$2" ....  

Prompting

Many people like to have the shell provide them with useful information in their prompt. To accommodate this, the shell recognises special sequences of characters in the values of PS1 and PS2, and substitutes the appropriate information for them. The special sequences and what they signify are:

%d

Place the current date, in the form DAY DD-MM-YY into the prompt.

%e

Place the current event number (as defined by the history command) into the prompt. If history evaluation has been turned off (via history -d), no number will be substituted in (i.e. the %e will be removed).

%n

Place the current working drive into the prompt.

%p

Place the current working directory into the prompt.

%t

Place the current time of day, in the form HH:MM into the prompt. The time is on a 24 hour clock, i.e. 1:30 in the afternoon will be 13:30.

%v

Place the MSDOS version number, in the form MSDOS MM:MM into the prompt.

%%

Place the character % into the prompt.

\xxx

Place the character \xxx into the prompt. The processing of escape sequences is the same as that for echo.

Some of these facilities are of more use than others.  

Input/Output

<word

Use file word as standard input (file descriptor 0).

>word

Use file word as standard output (file descriptor 1). If the file does not exist it is created; otherwise, it is truncated to zero length.

>>word

Use file word as standard output. If the file exists output is appended to it (by first seeking to the end-of-file); otherwise, the file is created.

<<[-]word

The shell input is read up to a line that is the same as word, or to an end-of-file. The resulting document becomes the standard input. If any character of word is quoted, no interpretation is placed upon the characters of the document; otherwise, parameter and command substitution occurs, (unescaped) \new-line is ignored, and \ must be used to quote the characters \, $, `, and the first character of word. If - is appended to <<, all leading tabs are stripped from word and from the document.

<&digit

Use the file associated with file descriptor digit as standard input. Similarly for the standard output using >&digit.

<&-

The standard input is closed. Similarly for the standard output using >&-.

If any of the above is preceded by a digit, the file descriptor which will be associated with the file is that specified by the digit (instead of the default 0 or 1). For example:

... 2>&1

associates file descriptor 2 with the file currently associated with file descriptor 1.

The order in which redirections are specified is significant. The shell evaluates redirections left-to-right. For example:

... 1>xxx 2>&1

first associates file descriptor 1 with file xxx. It associates file descriptor 2 with the file associated with file descriptor 1 (i.e. xxx). If the order of redirections were reversed, file descriptor 2 would be associated with the terminal (assuming file descriptor 1 had been) and file descriptor 1 would be associated with file xxx .

The environment for the execution of a command contains the file descriptors of the invoking shell as modified by input/output specifications.

Redirection of output is not allowed in the restricted shell.  

Environment

The environment for any simple-command may be augmented by prefixing it with one or more assignments to parameters. Thus:

TERM=450 cmd args                      and

(export TERM; TERM=450; cmd args)

are equivalent (as far as the execution of cmd is concerned).

If the -k flag is set, all keyword arguments are placed in the environment, even if they occur after the command name. The following first prints a=b c and c:

echo a=b c
set -k
echo a=b c

Signals

History

! [ str | num ] terminator

!num will place the history command with the specified number in the command line. !str will find the most recent command line that started with the characters in str.

The terminator determines what action is performed after the history line has been found. If the original history command is entered using the <return> key, the new command line is passed directly to the shell. If the <end> key is pressed, the new command line can be edited in the manner described below.  

Command Line Editing

Cursor Right

Move the cursor right one character

Control-Cursor Right

Move the cursor right one word

Cursor Left

Move the cursor left one character

Control-Cursor Left

Move the cursor left one word

Cursor Up

Get the previous command from the history file

Cursor Down

Get the next command from the history file

Insert

Toggle insert/overwrite mode

Delete

Delete the current character

Home

Move the cursor to the start of the command

End

Move the cursor to the end of the command, unless the first character of the command is a !, in which case the appropriate history search is done.

Control-End

Delete to the end of the line

Page-Up

Search backwards from the current history command for the next match against the last history request. This command can only be used after End has been used to select a history line.

Page-Down

Search forewards from the current history command for the next match against the last history request. This command can only be used after End has been used to select a history line.

Backspace

Move the cursor back one character, erasing the current character.

Return

Execute the command line, unless the first character of the command is a !, in which case the appropriate history processing is done.

Execution

The shell parameter PATH defines the search path for the directory containing the command. Alternative directory names are separated by a semi-colon (;). The default path is ;c:/bin;c:/usr/bin (specifying the current directory, c:/bin, and c:/usr/bin, in that order). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the semi-colon delimiters anywhere else in the path list. If the command name contains a / or starts with x: (where x is a drive letter) the search path is not used; such commands will not be executed by the restricted shell. Otherwise, each directory in the path is searched for an executable file.

If the file does not have a .com or .exe extension, it is opened and the first 5 characters are read. If the first 5 characters are the string #!sh\n it is assumed to be a file containing shell commands. Note that the shell will check the file and if that file does not exist or is not a script, it will try the file with an extension of .sh. If a .sh file is found, that will be processed. A sub-shell is spawned to read it. A parenthesized command is also executed in a sub-shell.  

Special Commands

:

No effect; the command does nothing. A zero exit code is returned.

letter:

Select the drive specified by letter.

. file

Read and execute commands from file and return. The search path specified by PATH is used to find the directory containing file.

break [ n ]

Exit from the enclosing for or while loop, if any. If n is specified, break n levels.

continue [ n ]

Resume the next iteration of the enclosing for or while loop. If n is specified, resume at the n-th enclosing loop.

cd [ arg ]

Change the current directory to arg. The shell parameter HOME is the default arg. The shell parameter CDPATH defines the search path for the directory containing arg. Alternative directory names are separated by a semi-colon (;). The default path is <null> (specifying the current directory). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the semi-colon delimiters anywhere else in the path list. If arg begins with a / or x: (where x is a drive letter), the search path is not used. Otherwise, each directory in the path is searched for arg. The cd command may not be executed by rsh.

echo [ arg ... ]

Echo arguments. Echo writes its arguments separated by blanks and terminated by a new-line on the standard output. It also understands C-like escape conventions; beware of conflicts with the shell's use of \:

\b

backspace

\c

print line without new-line

\f

form-feed

\n

new-line

\r

carriage return

\t

tab

\v

vertical tab

\\

backslash

\n

the 8-bit character whose ASCII code is the 1-, 2- or 3-digit octal number n, which must start with a zero.

Echo is useful for producing diagnostics in command files and for sending known data into a pipe.

eval [ arg ... ]

The arguments are read as input to the shell and the resulting command(s) executed.

exec [ arg ... ]

The command specified by the arguments is executed in place of this shell without creating a new process. Input/output arguments may appear and, if no other arguments are given, cause the shell input/output to be modified.

exit [ n ]

Causes a shell to exit with the exit status specified by n. If n is omitted the exit status is that of the last command executed (an end-of-file will also cause the shell to exit.)

export [ name ... ]

The given names are marked for automatic export to the environment of subsequently-executed commands. If no arguments are given, a list of all names that are exported in this shell is printed. Function names may not be exported.

getopt optstring name [ args ... ]

Parse command options and write them to standard output. Getopt is used to break up options in command lines for easy parsing by shell procedures and to check for legal options. Optstring is a string of recognized option letters (see getopt(3C)); if a letter is followed by a colon, the option is expected to have an argument which may or may not be separated from it by white space. The special option -- is used to delimit the end of the options. If it is used explicitly, getopt will recognize it; otherwise, getopt will generate it; in either case, getopt will place it at the end of the options. Each option is preceded by a - and is in its own positional parameter; each option argument is also parsed into its own positional parameter.

The following code fragment shows how one might process the arguments for a command that can take the options a or b, as well as the option o, which requires an argument:

then
     echo $USAGE
     exit 2
fi
for i in $*
do
     case $i in
     -a | -b)  FLAG=$i; shift;;
     -o)       OARG=$2; shift 2;;
     --)       shift; break;;
     esac
done

This code will accept any of the following as equivalent:

cmd -aoarg file file
cmd -a -o arg file file
cmd -oarg -a file file
cmd -a -oarg -- file file

history [ -dei ]

The history command, with no arguments, will print all the commands that are currently saved in the shell's history buffers. As new commands are executed, and space in the buffers runs out, old commands will be deleted. The history commands prints out the stored commands with sequence numbers. Negative numbered commands, through command number zero, are commands that were retrieved from the saved history file. Commands starting at one were entered during the current login session. If a saved command contains embedded newlines, these will be printed out as the sequence \n, so that individual command stay on one line.

The arguments changes the way the shell processes history information as follows:

-d

Disable the saving of commands in the history file.

-e

Enable the saving of commands in the history file.

-i

Initialise the history file.

msdos [ name ... ]

The given names are marked msdos format and if the -m flag is set, the values of the these names are exported to child processes with the any slashes in the value replaced by backslashes.

pwd

Print the current working directory.

read [ name ... ]

One line is read from the standard input and the first word is assigned to the first name, the second word to the second name, etc., with leftover words assigned to the last name. The return code is 0 unless an end-of-file is encountered.

readonly [ name ... ]

The given names are marked readonly and the values of the these names may not be changed by subsequent assignment. If no arguments are given, a list of all readonly names is printed.

return [ n ]

Causes a function to exit with the return value specified by n. If n is omitted, the return status is that of the last command executed.

set [ --aefkmntuvx [ arg ... ] ]

-a

Mark variables which are modified or created for export.

-e

Exit immediately if a command exits with a non-zero exit status.

-f

Disable file name generation

-k

All keyword arguments are placed in the environment for a command, not just those that precede the command name.

-m

For those variables marked as msdos variables, the values are exported to child processes with the slashes replaced by backslashes. Most MSDOS utilities do not care if a file name contains a slash or backslash as a directory separator. However, some like the linker require backslashes in the value of the LIB variable.

-n

Read commands but do not execute them.

-t

Exit after reading and executing one command.

-u

Treat unset variables as an error when substituting.

-v

Print shell input lines as they are read.

-x

Print commands and their arguments as they are executed.

--

Do not change any of the flags; useful in setting $1 to -.

Using + rather than - causes these flags to be turned off. These flags can also be used upon invocation of the shell. The current set of flags may be found in $-. The remaining arguments are positional parameters and are assigned, in order, to $1, $2, .... If no arguments are given the values of all names are printed.

shift [ n ]

The positional parameters from $n+1 ... are renamed $1 .... If n is not given, it is assumed to be 1.

swap [ options ]

This command defines how the shell will handle swapping. The options are

off

Disable swapping. The shell remains in memory whilst the child is running and reduces the available memory by about 200K (depending on the size of the environment and history).

on

Enable all devices. The shell will swap out to either expanded or extended memory or to disk, execute the command and then swap back in. Whilest swapped, the shell reduces the available memory by about 3K.

expand

Enable swapping to Expanded Memory. The EMS drive must exist on your system for this to work.

extent [ start address ]

Enable swapping to Extended Memory. The optional start address defines the based address in the Extended Memory at which point the shell writes its swap area. The default location is 0x100000.

disk

Enable swapping to disk. The shell creates a temporary file and saves itself in it. On completion, the file is deleted. This is the slowest method of swapping.

With no options, the current swapping options are displayed.

test expr or [ expr ]

Evaluate conditional expressions. Test evaluates the expression expr and, if its value is true, returns a zero (true) exit status; otherwise, a non-zero (false) exit status is returned; test also returns a non-zero exit status if there are no arguments. The following primitives are used to construct expr:

-r file

true if file exists and is readable.

-w file

true if file exists and is writable.

-x file

true if file exists and is executable.

-f file

true if file exists and is a regular file.

-d file

true if file exists and is a directory.

-c file

true if file exists and is a character special file.

-b file

true if file exists and is a block special file.

-s file

true if file exists and has a size greater than zero.

-t [ fildes ]

true if the open file whose file descriptor number is fildes (1 by default) is associated with a terminal device.

-n s1

true if the length of the string s1 is zero.

-n s1

true if the length of the string s1 is non-zero.

s1 = s2

true if strings s1 and s2 are identical.

s1 != s2

true if strings s1 and s2 are not identical.

s1

true if s1 is not the null string.

n1 -eq n2

true if the integers n1 and n2 are algebraically equal. Any of the comparisons -ne, -gt, -ge, -lt, and -le may be used in place of R-eq.

These primaries may be combined with the following operators:

!

unary negation operator.

-a

binary and operator.

-o

binary or operator (-a has higher precedence than -o).

( expr )

parentheses for grouping.

Notice that all the operators and flags are separate arguments to test. Notice also that parentheses are meaningful to the shell and, therefore, must be escaped.

trap [ arg ] [ n ] ...

The command arg is to be read and executed when the shell receives signal(s) n. (Note that arg is scanned once when the trap is set and once when the trap is taken.) Trap commands are executed in order of signal number. Any attempt to set a trap on a signal that was ignored on entry to the current shell is ineffective. An attempt to trap on signal 11 (memory fault) produces an error. If arg is absent all trap(s) n are reset to their original values. If arg is the null string this signal is ignored by the shell and by the commands it invokes. If n is 0 the command arg is executed on exit from the shell. The trap command with no arguments prints a list of commands associated with each signal number.

type [ name ... ]

For each name, indicate how it would be interpreted if used as a command name.

umask [ nnn ]

The user file-creation mask is set to nnn (see umask(2)). If nnn is omitted, the current value of the mask is printed.

unset [ name ... ]

For each name, remove the corresponding variable or function. The variables PATH, PS1, PS2, and IFS cannot be unset.

ver

Display the current version of the shell.

Invocation

-c string

If the -c flag is present commands are read from string.

-s

If the -s flag is present or if no arguments remain commands are read from the standard input. Any remaining arguments specify the positional parameters. Shell output (except for Special Commands) is written to file descriptor 2.

-i

If the -i flag is present or if the shell input and output are attached to a terminal, this shell is interactive. In this case, the TERMINATE signal is ignored and the INTERRUPT signal is caught and ignored. In all cases, the QUIT signal is ignored by the shell.

-r

If the -r flag is present, the shell is a restricted shell.

-0(zero)

If the -0(zero) flag is present, this has the same effect as starting the shell with the first character of argument zero as a - (see above).

The remaining flags and arguments are described under the set command above.  

Rsh Only

changing directory (see cd(1)),
setting the value of $PATH
specifying path or command names containing /,
redirecting output (> and >>).

The restrictions above are enforced after profile.sh is interpreted.

When a command to be executed is found to be a shell procedure, rsh invokes sh to execute it. Thus, it is possible to provide to the end-user shell procedures that have access to the full power of the standard shell, while imposing a limited menu of commands; this scheme assumes that the end-user does not have write and execute permissions in the same directory.

The net effect of these rules is that the writer of the profile.sh has complete control over user actions, by performing guaranteed setup actions and leaving the user in an appropriate directory (probably not the login directory).

The system administrator often sets up a directory of commands (i.e., /usr/rbin) that can be safely invoked by rsh. Some systems also provide a restricted editor red.  

EXIT STATUS

FILES

LIMIITATIONS

SEE ALSO

Index

NAME

SYNOPSIS

DESCRIPTION

Definitions

Commands

Comments

Command Substitution

Parameter Substitution

Blank Interpretation

File Name Generation

Quoting

Prompting

Input/Output

Environment

Signals

History

Command Line Editing

Execution

Special Commands

Invocation

Rsh Only

EXIT STATUS

FILES

LIMIITATIONS

SEE ALSO